RFC: Reorganize docs into 3 site sections by louis-pre · Pull Request #1060 · seamapi/docs

louis-pre · 2026-04-10T21:53:07Z

Summary

Proposes splitting the current single-sidebar documentation (633 pages) into 3 GitBook site sections (Guides, API Reference, Brand Guides).

What's in this PR

docs-reorganization-plan.md — full plan with problem statement, 3-section proposal, trade-offs, and open questions
plan/ — step 1 (sectioning) and step 2 (reorganization) with before/after sidebar trees

Proposed sections

Section	Pages	Audience
Guides	~120	Developers learning Seam / implementing features
API Reference	~240	Developers looking up endpoints, SDK docs, rate limits
Brand Guides	~160	Developers integrating a specific device brand

Guides: organized by product type

Product	What it covers
Access	Access Grants & Identity (high-level), Smart Locks & Access Codes (low-level), Access Control Systems (low-level)
Thermostats	HVAC modes, climate presets, schedules, programs
Noise Sensors	Noise threshold configuration

Cross-product features (Connectors & Automations, Customer Portals, Reservation Automations) have their own section (location TBD). Developer Tools includes Webhooks, CLI, MCP, Mobile SDKs, Seam Components, and Seam Mobile Components.

API Reference: mirrors Guides structure

API endpoints are organized by the same product types as Guides (Access, Thermostats, Noise Sensors, Connectors & Automations), plus a Platform section for cross-cutting resources (Devices, Events, Webhooks, Workspaces, etc.).

Brand Guides: organized by device category

Per-manufacturer setup, configuration, getting started guides, and sandbox data — all consolidated by brand and organized by device category (Smart Locks, Access Control Systems, Thermostats, Other).

Key decisions to make

Are we on GitBook Ultimate, or willing to upgrade? (site sections require Ultimate at $249/site/mo)
Where should Device Manufacturer Guidance live? => moving it at the end of the brand guides for now
SDKs and UI component libraries should have content in both Guides (setup, usage, tutorials) and API Reference (API surface, parameters, methods). Need to define the split for each.
Where should Connectors & Automations live?
How do we maintain backward compatibility for existing page URLs during the migration? (redirects strategy TBD)

No content changes

This PR only adds planning documents. No existing docs are moved or modified.

🤖 Generated with Claude Code

linear · 2026-04-16T22:48:42Z

ENG-1191 Reorganize docs into new site sections

Review in Linear

louis-pre · 2026-04-16T23:16:10Z

+├── Smart Locks (each with setup + sandbox)
+├── Access Control Systems (each with setup + sandbox)
+├── Thermostats (each with setup + sandbox)
+├── Other Devices & Systems


Not sure if that split makes sense, some providers might span multiple sections

i agree. we might want to not organize by brand. Some examples that come to mind: Eufy (locks, thermostat, vacuum...etc); Lockly (lock, doorbell..etc)

dawnho · 2026-04-16T23:29:36Z

+│   ├── Access Grants & Identity
+│   │   ├── Access Grants (create, update, delete, retrieve, deliver methods, reservation grants)
+│   │   ├── Instant Keys (how they work, setup, issuing, delivering)
+│   │   └── User Identities (managing accounts, managing phones)


Should user identities only live within the context of Access?

I mention it in the "Mapping Resources" section

Are they used for anything outside of access?

The mapping resources section is about the keys right?

dawnho · 2026-04-16T23:30:55Z

+│   └── Action Attempts
+├── Access
+│   ├── Access Grants & Identity
+│   │   ├── Access Grants (create, update, delete, retrieve, deliver methods, reservation grants)


Optix channel has a lot of good questions about all the other api methods needed for building the ui they wanted.

Listing entrances / devices a user has, and knowing which unlock method (mobile key, unlock) is available for it.

dawnho · 2026-04-16T23:32:13Z

+│   ├── Webhooks
+│   ├── Seam CLI
+│   ├── Seam MCP Server
+│   ├── Mobile SDKs (Android, iOS)


Should the mobile sdk reference have its own top level section too?

Good question! Could be either considered a full fledged feature or a developer tool

I think it's more a product decision on how much we want to highlight them, if you say we should then let's move them up

louis-pre · 2026-04-17T21:16:01Z

Talking with Evan, I think it makes more sense to make this migration into 3 broad phases

Easy stuff => split in 3 sections (Guides, API Reference and Integrations)
Figure out the entrypoint triage and customer implementation paths (hard)
Figure out API reference migration if necessary (or keep it flat if we consider that users already know what they're looking for)

sybohy · 2026-04-17T21:34:26Z

+
+**Audience:** Developers learning Seam or implementing specific features.
+
+**Organized by product type.** The Guides sidebar groups content by product vertical:


Maybe rename sections to more broader themes. Otherwise we end up with a tab for each device category?
- thermostat → “energy”
- noise sensors → “sensors”
- camera+

sybohy · 2026-04-17T21:34:41Z

+| **Thermostats**   | HVAC modes, climate presets, schedules, programs                                                                  |
+| **Noise Sensors** | Noise threshold configuration                                                                                     |
+
+Cross-product features (Connectors & Automations, Customer Portals, Reservation Automations) have their own section. Developer workflow tools (Webhooks, CLI, MCP, Mobile SDKs) live in Developer Tools. UI Components (Seam Components, Seam Mobile Components) are in their own section for now.


Maybe add two more menus: Embeddable UIs and Automations?

sybohy · 2026-04-17T21:36:54Z

Summarizing most of my comments

Maybe rename thermostat/noise-sensor sections to more broader themes. Otherwise we end up with a tab for each device category? So like:
- thermostat → “energy”
- noise sensors → “sensors”
- camera+
Maybe add two more menus: Embeddable UIs and Automations?
- These can then be referenced from other places?
Do we need anything for Connectors or can we ignore?
Device guides → maybe “brand guides”
“How do we maintain backward compatibility for existing page URLs during the migration” → this is very important for SEO

Proposes splitting the current single-sidebar documentation (633 pages) into 4 GitBook site sections: Guides, API Reference, Integrations, and UI Components. Includes draft SUMMARY.md files for each section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Audits all URL prefixes per sidebar section, identifying 89 entries (14%) at paths that don't match their section. Proposes target path structure: - guides/ for all conceptual + how-to content - api/ unchanged - integrations/ consolidating 4 legacy directories - ui/ for web and mobile components Eliminates 5 legacy directories and shortens 1. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Wildcard redirects break when pages are later renamed (the wildcard mechanically swaps the prefix but doesn't track renames → 404). Recommends scripted generation of explicit per-page redirects, uploaded via CSV. ~560 total redirects in 2 batches. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Reorganizes the Guides sidebar to reflect Seam Connect's 3 abstraction layers instead of grouping by device type: - Layer 1: Connectors & Automations (highest abstraction) - Layer 2: Access Grants & Identity (core access model) - Layer 3: Device & System APIs (smart locks, ACS, thermostats, sensors) Seam Bridge moved under ACS in Layer 3. Cross-cutting concerns (webhooks, CLI, rate limits) stay in Developer Tools. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace the 4-section / 3-layer architecture with a simpler 3-section model (Guides, Developer Reference, Integrations) organized by product type (Access, Thermostats, Noise Sensors) instead of abstraction layer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…rence Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Step 1: Split docs into 3 site sections (Guides, API Reference, Brand Guides) keeping current sidebar structure within each. Step 2: Reorganize content by product type within each section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- plan/step_1/ — simple 3-way section split - plan/step_2/ — content reorganization per section (guides, api-reference, brand-guides) with before/after trees - Remove old proposed-summaries/ directory Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers: directory structure, cross-section links, codegen changes, shared assets, sandbox data, misplaced files, git sync, and redirects. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

louis-pre requested a review from a team as a code owner April 10, 2026 21:53

seambot requested a review from a team as a code owner April 10, 2026 21:56

louis-pre changed the title ~~RFC: Reorganize docs into 4 site sections~~ RFC: Reorganize docs into 3 site sections by product type Apr 16, 2026

louis-pre changed the title ~~RFC: Reorganize docs into 3 site sections by product type~~ RFC: Reorganize docs into 3 site sections Apr 16, 2026

louis-pre commented Apr 16, 2026

View reviewed changes

Comment thread docs/api/customers/create_portal.md

louis-pre commented Apr 16, 2026

View reviewed changes

Comment thread proposed-summaries/step-2-site-structure.md Outdated

louis-pre commented Apr 16, 2026

View reviewed changes

dawnho reviewed Apr 16, 2026

View reviewed changes

Comment thread proposed-summaries/site-structure.md Outdated

dawnho reviewed Apr 16, 2026

View reviewed changes

sybohy approved these changes Apr 17, 2026

View reviewed changes

This was referenced Apr 21, 2026

Move all files to match their SUMMARY.md section headings #1079

Merged

feat: Add Brand Guides site section #1084

Merged

louis-pre and others added 13 commits April 23, 2026 13:01

ci: Format code

9fb6f0a

ci: Format code

cd8fc10

ci: Format code

4e8344a

ci: Format code

5a85dfa

ci: Format code

2138302

Remove old SUMMARY files, site-structure.md is the source of truth

eda7603

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove path audit, will revisit later

bc098d9

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mark Connectors & Automations location as TBD

f2f2847

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

louis-pre and others added 15 commits April 23, 2026 13:02

Fix UI Components TBD: content split across Guides and Developer Refe…

d6b2af0

…rence Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Move UI Components under Developer Tools

eee3b6e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mark Seam Bridge location as TBD

6c44a67

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace file path consolidation concern with URL backward compatibility

a6efff0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rename Developer Reference to API Reference

63756cd

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ci: Format code

eabc3c9

ci: Format code

3c7fda0

ci: Format code

430dad8

Expand step 1 plan with technical concerns

39415ef

Covers: directory structure, cross-section links, codegen changes, shared assets, sandbox data, misplaced files, git sync, and redirects. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ci: Format code

483f4fe

Add note on mitigating cross-section URL sprawl via codegen config

9e7a282

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add step 2 README with TODOs for get started, core concepts, and more

4acd484

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ci: Format code

ede0fb3

louis-pre force-pushed the docs-reorganization-plan branch from 60c8b38 to ede0fb3 Compare April 23, 2026 20:02


		Audience: Developers learning Seam or implementing specific features.

		Organized by product type. The Guides sidebar groups content by product vertical:

Conversation

louis-pre commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's in this PR

Proposed sections

Guides: organized by product type

API Reference: mirrors Guides structure

Brand Guides: organized by device category

Key decisions to make

No content changes

Uh oh!

linear Bot commented Apr 16, 2026 • edited by linear-code Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

louis-pre commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sybohy commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

louis-pre commented Apr 10, 2026 •

edited

Loading

linear Bot commented Apr 16, 2026 •

edited by linear-code Bot

Loading